Autocomplete

The Autocomplete component offers simple and flexible type-ahead functionality.

It is great for searching a value from a long list of options. In comparison to a Select, the Autocomplete doesn't need to know the complete item list, it only calls a search function which will return matching items. The search function can even run asynchronously, i.e. for database queries.

Note: Blazor static rendering is not supported. See install guide for more info.

Visual Playground

@using MudBlazor

<MudStack Row Class="justify-space-between mud-width-full">
    <MudStack Style="width: 300px">
        @foreach (var variant in Enum.GetValues(typeof(Variant)).Cast<Variant>())
        {
            <MudAutocomplete @bind-Value="_value"
                             SearchFunc="Search"
                             Variant="variant"
                             Label="@variant.ToString()"
                             Margin="_margin"
                             Dense="_dense"
                             Disabled="_disabled"
                             ReadOnly="_readonly"
                             Placeholder="@(_placeholder ? "Placeholder" : null)"
                             HelperText="@(_helperText ? "Helper Text" : null)"
                             HelperTextOnFocus="_helperTextOnFocus"
                             Clearable="_clearable" />
        }
    </MudStack>

    <MudStack>
        <MudSelect @bind-Value="_margin" Label="Margin">
            @foreach (var margin in Enum.GetValues(typeof(Margin)).Cast<Margin>())
            {
                <MudSelectItem Value="margin">@margin</MudSelectItem>
            }
        </MudSelect>

        <MudSwitch @bind-Value="_dense" Label="Dense" Color="Color.Primary" />
        <MudSwitch @bind-Value="_readonly" Label="ReadOnly" Color="Color.Primary" />
        <MudSwitch @bind-Value="_disabled" Label="Disabled" Color="Color.Primary" />
        <MudSwitch @bind-Value="_placeholder" Label="Placeholder" Color="Color.Primary" />
        <MudSwitch @bind-Value="_helperText" Label="HelperText" Color="Color.Primary" />
        <MudSwitch @bind-Value="_helperTextOnFocus" Label="HelperTextOnFocus" Color="Color.Primary" />
        <MudSwitch @bind-Value="_clearable" Label="Clearable" Color="Color.Primary" />
    </MudStack>
</MudStack>

@code {
    string _value;
    Margin _margin;
    bool _dense;
    bool _disabled;
    bool _readonly;
    bool _placeholder;
    bool _helperText;
    bool _helperTextOnFocus;
    bool _clearable;

    private string[] _states =
    {
        "Alabama", "Alaska", "Arizona", "Arkansas", "California",
        "Colorado", "Connecticut", "Delaware", "Florida", "Georgia",
        "Hawaii", "Idaho", "Illinois", "Indiana", "Iowa", "Kansas",
        "Kentucky", "Louisiana", "Maine", "Maryland", "Massachusetts",
        "Michigan", "Minnesota", "Mississippi", "Missouri", "Montana",
        "Nebraska", "Nevada", "New Hampshire", "New Jersey", "New Mexico",
        "New York", "North Carolina", "North Dakota", "Ohio", "Oklahoma",
        "Oregon", "Pennsylvania", "Rhode Island", "South Carolina", "South Dakota",
        "Tennessee", "Texas", "Utah", "Vermont", "Virginia",
        "Washington", "West Virginia", "Wisconsin", "Wyoming"
    };

    private async Task<IEnumerable<string>> Search(string value, CancellationToken token)
    {
        // In real life use an asynchronous function for fetching data from an api.
        await Task.Delay(5, token);

        // if text is null or empty, show complete list
        if (string.IsNullOrEmpty(value))
            return _states;

        return _states.Where(x => x.Contains(value, StringComparison.InvariantCultureIgnoreCase));
    }
}
Usage

How you write the search function determines whether or not the Autocomplete shows a full list initially. By setting ResetValueOnEmptyText="true", the Value will be reset when the user clears the input text. With CoerceText="true" upon selection of an entry from the list, the Text is always updated. When the user types something that is not on the list and CoerceValue is true, the Value will be overwritten with the user input which allows it to be passed to the validation function.

Not selected
Not selected

@using System.Threading

<MudGrid>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="string" Label="US States" @bind-Value="value1" SearchFunc="@Search1"
                         ResetValueOnEmptyText="@resetValueOnEmptyText"
                         CoerceText="@coerceText" CoerceValue="@coerceValue" />
    </MudItem>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="string" Label="US States" @bind-Value="value2" SearchFunc="@Search2"
                         ResetValueOnEmptyText="@resetValueOnEmptyText"
                         CoerceText="@coerceText" CoerceValue="@coerceValue"
                         AdornmentIcon="@Icons.Material.Filled.Search" AdornmentColor="Color.Primary" />
    </MudItem>
    <MudItem xs="12" md="12">
        <MudText Class="mb-n3" Typo="Typo.body2">
            <MudChip T="string">@(value1 ?? "Not selected")</MudChip><MudChip T="string">@(value2 ?? "Not selected")</MudChip>
        </MudText>
    </MudItem>
    <MudItem xs="12" md="12" class="flex-column">
        <MudSwitch @bind-Value="resetValueOnEmptyText" Color="Color.Primary">Reset Value on empty Text</MudSwitch>
        <MudSwitch @bind-Value="coerceText" Color="Color.Secondary">Coerce Text to Value</MudSwitch>
        <MudSwitch @bind-Value="coerceValue" Color="Color.Tertiary">Coerce Value to Text (if not found)</MudSwitch>
    </MudItem>
</MudGrid>

@code {
    private bool resetValueOnEmptyText;
    private bool coerceText;
    private bool coerceValue;
    private string value1, value2;
    private string[] states =
    {
        "Alabama", "Alaska", "American Samoa", "Arizona",
        "Arkansas", "California", "Colorado", "Connecticut",
        "Delaware", "District of Columbia", "Federated States of Micronesia",
        "Florida", "Georgia", "Guam", "Hawaii", "Idaho",
        "Illinois", "Indiana", "Iowa", "Kansas", "Kentucky",
        "Louisiana", "Maine", "Marshall Islands", "Maryland",
        "Massachusetts", "Michigan", "Minnesota", "Mississippi",
        "Missouri", "Montana", "Nebraska", "Nevada",
        "New Hampshire", "New Jersey", "New Mexico", "New York",
        "North Carolina", "North Dakota", "Northern Mariana Islands", "Ohio",
        "Oklahoma", "Oregon", "Palau", "Pennsylvania", "Puerto Rico",
        "Rhode Island", "South Carolina", "South Dakota", "Tennessee",
        "Texas", "Utah", "Vermont", "Virgin Island", "Virginia",
        "Washington", "West Virginia", "Wisconsin", "Wyoming",
    };

    private async Task<IEnumerable<string>> Search1(string value, CancellationToken token)
    {
        // In real life use an asynchronous function for fetching data from an api.
        await Task.Delay(5, token);

        // if text is null or empty, show complete list
        if (string.IsNullOrEmpty(value))
            return states;
        return states.Where(x => x.Contains(value, StringComparison.InvariantCultureIgnoreCase));
    }

    private async Task<IEnumerable<string>> Search2(string value, CancellationToken token)
    {
        // In real life use an asynchronous function for fetching data from an api.
        await Task.Delay(5, token);

        // if text is null or empty, don't return values (drop-down will not open)
        if (string.IsNullOrEmpty(value))
            return new string[0];
        return states.Where(x => x.Contains(value, StringComparison.InvariantCultureIgnoreCase));
    }
}
Presentation

When you use objects, Autocomplete uses ToString() to convert the object into text form. You can set a custom ToStringFunc to override how the list items are stringified. This string representation is also what you'll get as input to the search function.
If that is not enough, you can define the following templates <ItemTemplate>, <ItemSelectedTemplate>, and <ItemDisabledTemplate> to create highly sophisticated list item presentations.

Selected values:

Not selected
Not selected
Not selected

@using System.Net.Http.Json
@using MudBlazor.Examples.Data.Models
@using System.Threading
@inject HttpClient httpClient

<MudGrid>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value1" 
                         SearchFunc="@Search" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")" />
    </MudItem>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value2" 
                         SearchFunc="@Search" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")">
            <ItemTemplate Context="e">                          
                <MudText>
                    <MudIcon Icon="@Icons.Material.Filled.CheckBoxOutlineBlank" Class="mb-n1 mr-3"/>@($"{e.Name} ({e.Sign})")
                </MudText>
            </ItemTemplate>
            <ItemSelectedTemplate Context="e">                
                <MudText>
                    <MudIcon Icon="@Icons.Material.Filled.CheckBox" Class="mb-n1 mr-3"/>@($"{e.Name} ({e.Sign})")
                </MudText>
            </ItemSelectedTemplate>
        </MudAutocomplete>
    </MudItem>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value3"
                   SearchFunc="@Search" ItemDisabledFunc="@((Element e) => (e.Name.Contains("H")))" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")">
            <ItemDisabledTemplate>
                <MudText>Not available: @context.ToString()</MudText>
            </ItemDisabledTemplate>
        </MudAutocomplete>
    </MudItem>
    <MudItem xs="12" md="12">
        <MudText Class="mb-n3" Typo="Typo.body2">
            Selected values: <MudChip T="string">@(value1?.ToString() ?? "Not selected")</MudChip><MudChip T="string">@(value2?.ToString() ?? "Not selected")</MudChip><MudChip T="string">@(value3?.ToString() ?? "Not selected")</MudChip>
        </MudText>
    </MudItem>
</MudGrid>

@code {
    private Element value1, value2, value3;

    private async Task<IEnumerable<Element>> Search(string value, CancellationToken token)
    {
        return  await httpClient.GetFromJsonAsync<List<Element>>($"webapi/periodictable/{value}", token);
    }
}
Presentation Extras

You can also define a <MoreItemsTemplate> to handle the case where the search returns more items than the list is configured to show and a <NoItemsTemplate> that presents some default content if the search returns no results. For your own custom content that always shows at the top or the bottom of the list define the <BeforeItemsTemplate> and the <AfterItemsTemplate>. 

@using System.Net.Http.Json
@using MudBlazor.Examples.Data.Models
@using System.Threading
@inject HttpClient httpClient

<MudGrid>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value1"
                         SearchFunc="@Search" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")">
            <MoreItemsTemplate>
                <MudText Align="Align.Center" Class="px-4 py-1">
                    Only the first 10 items are shown
                </MudText>
            </MoreItemsTemplate>
        </MudAutocomplete>
    </MudItem>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value2"
                         SearchFunc="@SearchEmpty" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")">
            <NoItemsTemplate>
                <MudText Align="Align.Center" Class="px-4 py-1">
                    No items found
                </MudText>
            </NoItemsTemplate>
        </MudAutocomplete>
    </MudItem>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value3"
                         SearchFunc="@Search" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")">
            <BeforeItemsTemplate>
                <MudText Color="Color.Primary" Class="px-4 py-1">Always Shows Before List</MudText>
            </BeforeItemsTemplate>
        </MudAutocomplete>
    </MudItem>
    <MudItem xs="12" sm="6" md="4">
        <MudAutocomplete T="Element" Label="Periodic Table Element" @bind-Value="value4"
                         SearchFunc="@Search" ToStringFunc="@(e=> e==null?null : $"{e.Name} ({e.Sign})")">
            <AfterItemsTemplate>
                <div class="pa-2">
                    <MudButton Color="Color.Primary">Add Item(does nothing)</MudButton>
                </div>
            </AfterItemsTemplate>
        </MudAutocomplete>
    </MudItem>
</MudGrid>

@code {
    private Element value1, value2, value3, value4;

    private async Task<IEnumerable<Element>> Search(string value, CancellationToken token)
    {
        return await httpClient.GetFromJsonAsync<List<Element>>($"webapi/periodictable/{value}", token);
    }

    private async Task<IEnumerable<Element>> SearchEmpty(string value, CancellationToken token)
    {
        await Task.Delay(5, token);
        return Array.Empty<Element>();
    }
}
An error has occurred. This application may no longer respond until reloaded. Reload 🗙